A JSON Schema Transformation (JST) in simple terms is the transformation of data usually from a web-based application to a company’s internal database or vice versa. Transferred JSON data has to be reformatted in order to work with other applications not written in JSON or if the data is in a different non-JSON format.
The Itential Automation Platform (IAP) has a built-in JSON Schema Transformation Tool which allows you to leverage pre-built templates that are editable or you can create a new transformation. This guide will illustrate how to use both the pre-builts and how to build your own transformation utilizing the JST Tool.
Create a New JST
To access the transformation tool and create a new JST:
Go to IAP → Automation Studio → Transformations.
Figure 1: Transformations
From the Transformations collection menu, you can search for an existing JST or select one from the dropdown list.
To create a new JST, click the plus sign (+) in the Transformations tab.
Figure 2: Create New
A blank canvas will open. This is where you will create your JST. Click the metadata icon to add a name to your JST (this is a mandatory field) and a description (this is an optional field).
Figure 3: Create New JST
Click the plus sign (+) to add an incoming schema.
Figure 4: Blank JST Canvas
There are three (3) different ways to add a new incoming schema:
- Cut and paste a schema into the left side window (editor).
- Paste the information in the right side window and click the Infer Schema From Example JSON link.
- Click the ↑ Schema upload button and navigate to the location of the JSON file you are going to use.
Figure 5: JSON Import Methods
For this example, the Infer Schema method was used to import the JSON.
- Paste the example JSON into the right side window and click the Infer Schema From Example JSON link.
- If the code is correct the Save button will become enabled and appear blue.
- Click Save and the incoming schema will appear on the Transformation canvas.
Figure 6: Infer Schema
The inferred schema created in the previous step is displayed under the Incoming Schemas column.
Figure 7: Incoming Schemas Column
Now the rest of JST can be built using the methods and functions in the column on the right side.
Figure 8: Methods & Functions
You can test your Transformation by clicking the Run button on the left side of the canvas. Lastly, make sure to save all changes, this will allow you to use the Transformation again.
Figure 9: Run & Save
Using Pre-Built JST
To use a pre-built JST:
Select the type of pre-built you want to use from the pre-built dropdown on the right side.
Type Description Template Example Allows you to concatenate (i.e., bring one or more) strings together while using embedded expressions and improving readability. Map Example Creates a new array with the results of a function that are used on every member in the calling array. Find Example Will return the value of the first element in the array that satisfies the provided testing function. If there is no element that meets the testing function, undefined is returned. Query Example Allows you to set the parameters of what you are searching for. The query should return any and all elements that meet the search criteria. Figure 10: Pre-built JSTs
Once you have selected a pre-built JST to use, click the Edit button above the incoming schema.
Figure 11: Edit Pre-built
Select the method for adding your data (i.e., cut/paste, infer, or upload) as referenced in the previous section.
Paste the JSON in the right code editor (white background) and click the Infer Schema From Example JSON link.
Figure 12: Infer Schema
Click Save to continue.
Figure 13: Save JSON
Once the JSON data is in the pre-built JST template, create (draw) connections between the incoming and outgoing schemas. When you select a field from the Incoming Schema column, the corresponding Outgoing Schemas fields will show blue if it is a match or red if it is not a match.
Important: The field types need to match (i.e., object to object, integer to integer, etc.).
Figure 14: Match Fields
Click the Run button to test.
Figure 15: Run to Test
The Output tab at the bottom of the canvas will display the results of running your JST.
Figure 16: Review Output
